<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="Content-Type" content="text/xhtml;charset=UTF-8"/>
<meta http-equiv="X-UA-Compatible" content="IE=9"/>
<title>BadgerDB: BadgerDB Documentation</title>

<link href="tabs.css" rel="stylesheet" type="text/css"/>
<link href="doxygen.css" rel="stylesheet" type="text/css" />

<link href="search/search.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="jquery.js"></script>
<script type="text/javascript" src="search/search.js"></script>
<script type="text/javascript">
  $(document).ready(function() { searchBox.OnSelectItem(0); });
</script>

</head>
<body>
<div id="top"><!-- do not remove this div! -->


<div id="titlearea">
<table cellspacing="0" cellpadding="0">
 <tbody>
 <tr style="height: 56px;">
  
  
  <td style="padding-left: 0.5em;">
   <div id="projectname">BadgerDB
   
   </div>
   
  </td>
  
  
  
 </tr>
 </tbody>
</table>
</div>

<!-- Generated by Doxygen 1.7.6.1 -->
<script type="text/javascript">
var searchBox = new SearchBox("searchBox", "search",false,'Search');
</script>
  <div id="navrow1" class="tabs">
    <ul class="tablist">
      <li class="current"><a href="index.html"><span>Main&#160;Page</span></a></li>
      <li><a href="namespaces.html"><span>Namespaces</span></a></li>
      <li><a href="annotated.html"><span>Classes</span></a></li>
      <li><a href="files.html"><span>Files</span></a></li>
      <li>
        <div id="MSearchBox" class="MSearchBoxInactive">
        <span class="left">
          <img id="MSearchSelect" src="search/mag_sel.png"
               onmouseover="return searchBox.OnSearchSelectShow()"
               onmouseout="return searchBox.OnSearchSelectHide()"
               alt=""/>
          <input type="text" id="MSearchField" value="Search" accesskey="S"
               onfocus="searchBox.OnSearchFieldFocus(true)" 
               onblur="searchBox.OnSearchFieldFocus(false)" 
               onkeyup="searchBox.OnSearchFieldChange(event)"/>
          </span><span class="right">
            <a id="MSearchClose" href="javascript:searchBox.CloseResultsWindow()"><img id="MSearchCloseImg" border="0" src="search/close.png" alt=""/></a>
          </span>
        </div>
      </li>
    </ul>
  </div>
</div>
<div class="header">
  <div class="headertitle">
<div class="title">BadgerDB Documentation </div>  </div>
</div><!--header-->
<div class="contents">
<div class="textblock"><h2><a class="anchor" id="toc_sec"></a>
Table of contents</h2>
<ol>
<li>
<a class="el" href="index.html#file_layout_sec">File layout</a> </li>
<li>
<a class="el" href="index.html#building_sec">Building and modifying the system</a> <ol>
<li>
<a class="el" href="index.html#prereq_sec">Prerequisites</a> </li>
<li>
<a class="el" href="index.html#commands_sec">Executing a build</a> </li>
<li>
<a class="el" href="index.html#modify_run_main_sec">Modifying and running main</a> </li>
<li>
<a class="el" href="index.html#documentation_sec">Rebuilding the documentation</a> </li>
</ol>
</li>
<li>
<a class="el" href="index.html#api_sec">BadgerDB API</a> <ol>
<li>
<a class="el" href="index.html#storage_sec">File storage</a> <ol>
<li>
<a class="el" href="index.html#file_management_sec">Creating, opening, and deleting files</a> </li>
<li>
<a class="el" href="index.html#file_data_sec">Reading and writing data in a file</a> </li>
<li>
<a class="el" href="index.html#page_sec">Reading and writing data in a page</a> </li>
</ol>
</li>
</ol>
</li>
</ol>
<h2><a class="anchor" id="file_layout_sec"></a>
File layout</h2>
<p>The files in this package are organized under the following hierarchy: </p>
<pre>
 docs/                  generated documentation
 src/                   code for BadgerDB
 </pre><p>You will likely be most interested in <code>src</code></p>
<h2><a class="anchor" id="building_sec"></a>
Building and modifying the system</h2>
<h3><a class="anchor" id="prereq_sec"></a>
Prerequisites</h3>
<p>To build and run the system, you need the following packages: </p>
<ul>
<li>
A modern C++ compiler (GCC &gt;= 4.6, any recent version of clang) </li>
<li>
Doxygen 1.6 or higher (for generating documentation only) </li>
</ul>
<p>The build system is configured to work on CSL RedHat 5 and 6 machines out of the box.</p>
<h3><a class="anchor" id="commands_sec"></a>
Executing a build</h3>
<p>All command examples are meant to be run at the command prompt from the <code>badgerdb</code> directory. When executing a command, omit the <code>$</code> prompt (so &ldquo;<code>$ make</code>&rdquo; means you just type &ldquo;<code>make</code>&rdquo; and press enter).</p>
<p>To build the executable: </p>
<div class="fragment"><pre class="fragment">   $ make
</pre></div><h3><a class="anchor" id="modify_run_main_sec"></a>
Modifying and running main</h3>
<p>To run the executable, first build the code, then run: </p>
<div class="fragment"><pre class="fragment">   $ ./src/badgerdb_main
</pre></div><p>If you want to edit what <code>badgerdb_main</code> does, edit <code><a class="el" href="main_8cpp_source.html">src/main.cpp</a></code>.</p>
<h3><a class="anchor" id="documentation_sec"></a>
Rebuilding the documentation</h3>
<p>Documentation is generated by using Doxygen. If you have updated the documentation and need to regenerate the output files, run: </p>
<div class="fragment"><pre class="fragment">  $ make doc
</pre></div><p> Resulting documentation will be placed in the <code>docs/</code> directory; open <code>index.html</code> with your web browser to view it.</p>
<h2><a class="anchor" id="api_sec"></a>
BadgerDB API</h2>
<h3><a class="anchor" id="storage_sec"></a>
File storage</h3>
<p>Interaction with the underlying filesystem is handled by two classes: File and Page. Files store zero or more fixed-length pages; each page holds zero or more variable-length records.</p>
<p>Record data is represented using std::strings of arbitrary characters.</p>
<h4><a class="anchor" id="file_management_sec"></a>
Creating, opening, and deleting files</h4>
<p>Files must first be created before they can be used: </p>
<div class="fragment"><pre class="fragment">  <span class="comment">// Create and open a new file with the name &quot;filename.db&quot;.</span>
  <a class="code" href="classbadgerdb_1_1_file.html" title="Class which represents a file in the filesystem containing database pages.">badgerdb::File</a> new_file = <a class="code" href="classbadgerdb_1_1_file.html#a1fb708b45103a606f189850d6bf83a0c">badgerdb::File::create</a>(<span class="stringliteral">&quot;filename.db&quot;</span>);
</pre></div><p>If you want to open an existing file, use File::open like so: </p>
<div class="fragment"><pre class="fragment">  <span class="comment">// Open an existing file with the name &quot;filename.db&quot;.</span>
  <a class="code" href="classbadgerdb_1_1_file.html" title="Class which represents a file in the filesystem containing database pages.">badgerdb::File</a> existing_file = <a class="code" href="classbadgerdb_1_1_file.html#a8462afdbd250c0a483ddfbde144c8732">badgerdb::File::open</a>(<span class="stringliteral">&quot;filename.db&quot;</span>);
</pre></div><p>Multiple File objects share the same stream to the underlying file. The stream will be automatically closed when the last File object is out of scope; no explicit close command is necessary.</p>
<p>You can delete a file with File::remove: </p>
<div class="fragment"><pre class="fragment">  <span class="comment">// Delete a file with the name &quot;filename.db&quot;.</span>
  <a class="code" href="classbadgerdb_1_1_file.html#a1cc69467366badbd68021ac76a91190e">badgerdb::File::remove</a>(<span class="stringliteral">&quot;filename.db&quot;</span>);
</pre></div><h4><a class="anchor" id="file_data_sec"></a>
Reading and writing data in a file</h4>
<p>Data is added to a File by first allocating a Page, populating it with data, and then writing the Page back to the File.</p>
<p>For example: </p>
<div class="fragment"><pre class="fragment"><span class="preprocessor">   #include &quot;file.h&quot;</span>

   ...

   <span class="comment">// Write a record with the value &quot;hello, world!&quot; to the file.</span>
   <a class="code" href="classbadgerdb_1_1_file.html" title="Class which represents a file in the filesystem containing database pages.">badgerdb::File</a> db_file = <a class="code" href="classbadgerdb_1_1_file.html#a8462afdbd250c0a483ddfbde144c8732">badgerdb::File::open</a>(<span class="stringliteral">&quot;filename.db&quot;</span>);
   <a class="code" href="classbadgerdb_1_1_page.html" title="Class which represents a fixed-size database page containing records.">badgerdb::Page</a> new_page = db_file.<a class="code" href="classbadgerdb_1_1_file.html#a7d0e047bcc8dc4cee36aac5b2060bbe3">allocatePage</a>();
   new_page.<a class="code" href="classbadgerdb_1_1_page.html#ad0b1e85fe7849fb767dd8c21a8053cf4">insertRecord</a>(<span class="stringliteral">&quot;hello, world!&quot;</span>);
   db_file.<a class="code" href="classbadgerdb_1_1_file.html#a9a1b3cc43c4631bde58c1c4f670e1036">writePage</a>(new_page);
</pre></div><p>Pages are read back from a File using their page numbers: </p>
<div class="fragment"><pre class="fragment"><span class="preprocessor">   #include &quot;file.h&quot;</span>
<span class="preprocessor">   #include &quot;page.h&quot;</span>

   ...

   <span class="comment">// Allocate a page and then read it back.</span>
   <a class="code" href="classbadgerdb_1_1_page.html" title="Class which represents a fixed-size database page containing records.">badgerdb::Page</a> new_page = db_file.<a class="code" href="classbadgerdb_1_1_file.html#a7d0e047bcc8dc4cee36aac5b2060bbe3">allocatePage</a>();
   db_file.<a class="code" href="classbadgerdb_1_1_file.html#a9a1b3cc43c4631bde58c1c4f670e1036">writePage</a>(new_page);
   <span class="keyword">const</span> <a class="code" href="namespacebadgerdb.html#a1f49e404293bf4240756b89b53b1587a" title="Identifier for a page in a file.">badgerdb::PageId</a>&amp; page_number = new_page.<a class="code" href="classbadgerdb_1_1_page.html#af55a0b44876bff4d513bdbed8bc8c5a3">page_number</a>();
   <a class="code" href="classbadgerdb_1_1_page.html" title="Class which represents a fixed-size database page containing records.">badgerdb::Page</a> same_page = db_file.<a class="code" href="classbadgerdb_1_1_file.html#aba4762b533499b7b7cc0774192ead27c">readPage</a>(page_number);
</pre></div><p>You can also iterate through all pages in the File: </p>
<div class="fragment"><pre class="fragment"><span class="preprocessor">   #include &quot;file_iterator.h&quot;</span>

   ...

   <span class="keywordflow">for</span> (<a class="code" href="classbadgerdb_1_1_file_iterator.html" title="Iterator for iterating over the pages in a file.">badgerdb::FileIterator</a> iter = db_file.<a class="code" href="classbadgerdb_1_1_file.html#a32e94f392eb3740dd9eb9101b9e09d47">begin</a>();
        iter != db_file.<a class="code" href="classbadgerdb_1_1_file.html#a01e224676a67634f21d53fc4189b8f11">end</a>();
        ++iter) {
     std::cout &lt;&lt; <span class="stringliteral">&quot;Read page: &quot;</span> &lt;&lt; iter-&gt;page_number() &lt;&lt; std::endl;
   }
</pre></div><h4><a class="anchor" id="page_sec"></a>
Reading and writing data in a page</h4>
<p>Pages hold variable-length records containing arbitrary data.</p>
<p>To insert data on a page: </p>
<div class="fragment"><pre class="fragment"><span class="preprocessor">   #include &quot;page.h&quot;</span>

   ...

   <a class="code" href="classbadgerdb_1_1_page.html" title="Class which represents a fixed-size database page containing records.">badgerdb::Page</a> new_page;
   new_page.<a class="code" href="classbadgerdb_1_1_page.html#ad0b1e85fe7849fb767dd8c21a8053cf4">insertRecord</a>(<span class="stringliteral">&quot;hello, world!&quot;</span>);
</pre></div><p>Data is read by using RecordIds, which are provided when data is inserted: </p>
<div class="fragment"><pre class="fragment"><span class="preprocessor">   #include &quot;page.h&quot;</span>

   ...

   <a class="code" href="classbadgerdb_1_1_page.html" title="Class which represents a fixed-size database page containing records.">badgerdb::Page</a> new_page;
   <span class="keyword">const</span> <a class="code" href="structbadgerdb_1_1_record_id.html" title="Identifier for a record in a page.">badgerdb::RecordId</a>&amp; rid = new_page.<a class="code" href="classbadgerdb_1_1_page.html#ad0b1e85fe7849fb767dd8c21a8053cf4">insertRecord</a>(<span class="stringliteral">&quot;hello, world!&quot;</span>);
   new_page.<a class="code" href="classbadgerdb_1_1_page.html#a77b352920c3e66384317bbcdcd900d99">getRecord</a>(rid); <span class="comment">// returns &quot;hello, world!&quot;</span>
</pre></div><p>As Pages use std::string to represent data, it's very natural to insert strings; however, any data can be stored: </p>
<div class="fragment"><pre class="fragment"><span class="preprocessor">   #include &quot;page.h&quot;</span>

   ...

   <span class="keyword">struct </span>Point {
     <span class="keywordtype">int</span> x;
     <span class="keywordtype">int</span> y;
   };
   Point new_point = {10, -5};
   <a class="code" href="classbadgerdb_1_1_page.html" title="Class which represents a fixed-size database page containing records.">badgerdb::Page</a> new_page;
   std::string new_data(reinterpret_cast&lt;char*&gt;(&amp;new_point),
                        <span class="keyword">sizeof</span>(new_point));
   <span class="keyword">const</span> <a class="code" href="structbadgerdb_1_1_record_id.html" title="Identifier for a record in a page.">badgerdb::RecordId</a>&amp; rid = new_page.<a class="code" href="classbadgerdb_1_1_page.html#ad0b1e85fe7849fb767dd8c21a8053cf4">insertRecord</a>(new_data);
   Point read_point =
       *<span class="keyword">reinterpret_cast&lt;</span><span class="keyword">const </span>Point*<span class="keyword">&gt;</span>(new_page.<a class="code" href="classbadgerdb_1_1_page.html#a77b352920c3e66384317bbcdcd900d99">getRecord</a>(rid).data());
</pre></div><p> Note that serializing structures like this is not industrial strength; it's better to use something like Google's protocol buffers or Boost serialization.</p>
<p>You can also iterate through all records in the Page: </p>
<div class="fragment"><pre class="fragment"><span class="preprocessor">   #include &quot;page_iterator.h&quot;</span>

   ...

   <span class="keywordflow">for</span> (<a class="code" href="classbadgerdb_1_1_page_iterator.html" title="Iterator for iterating over the records in a page.">badgerdb::PageIterator</a> iter = new_page.<a class="code" href="classbadgerdb_1_1_page.html#aa0fdb281074cd60cb1f1d6ea6d620772">begin</a>();
        iter != new_page.<a class="code" href="classbadgerdb_1_1_page.html#a8e78cba69bef682a5427932485da4608">end</a>();
        ++iter) {
     std::cout &lt;&lt; <span class="stringliteral">&quot;Record data: &quot;</span> &lt;&lt; *iter &lt;&lt; std::endl;
   }
</pre></div> </div></div><!-- contents -->
<!-- window showing the filter options -->
<div id="MSearchSelectWindow"
     onmouseover="return searchBox.OnSearchSelectShow()"
     onmouseout="return searchBox.OnSearchSelectHide()"
     onkeydown="return searchBox.OnSearchSelectKey(event)">
<a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(0)"><span class="SelectionMark">&#160;</span>All</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(1)"><span class="SelectionMark">&#160;</span>Classes</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(2)"><span class="SelectionMark">&#160;</span>Namespaces</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(3)"><span class="SelectionMark">&#160;</span>Functions</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(4)"><span class="SelectionMark">&#160;</span>Variables</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(5)"><span class="SelectionMark">&#160;</span>Typedefs</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(6)"><span class="SelectionMark">&#160;</span>Friends</a></div>

<!-- iframe showing the search results (closed by default) -->
<div id="MSearchResultsWindow">
<iframe src="javascript:void(0)" frameborder="0" 
        name="MSearchResults" id="MSearchResults">
</iframe>
</div>



<hr class="footer"/><address class="footer"><small>
Generated on Wed Jan 30 2013 14:17:57 for BadgerDB by &#160;<a href="http://www.doxygen.org/index.html">
<img class="footer" src="doxygen.png" alt="doxygen"/>
</a> 1.7.6.1
</small></address>

</body>
</html>
